Implement ANTS-2D bifacial irradiance model by kandersolar · Pull Request #2740 · pvlib/pvlib-python

kandersolar · 2026-04-21T19:52:53Z

~~[ ] Closes #xxxx~~
I am familiar with the contributing guidelines
I attest that all AI-generated material has been vetted for accuracy and is in compliance with the pvlib license
Tests added
Updates entries in docs/sphinx/source/reference for API changes.
Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
Pull request is nearly complete and ready for detailed review.
Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

@AdamRJensen, @cwhanse, and I have a paper describing a new bifacial irradiance model called ANTS-2D. It is similar to pvlib's infinite_sheds model, but extended to allow:

a discretized module surface (for, e.g., cell-level irradiance values)
a discretized ground surface, with variable albedo
sloped terrain, in the fashion of pvlib's existing functionality in that area
the Perez transposition model, in addition to Hay-Davies and isotropic
computation of ground-level irradiance (for agriPV)
fast computation by using analytical integrated view factors instead of burdensome numerical integrals

Details available open-access here: https://doi.org/10.1109/JPHOTOV.2026.3677506

This PR is rather large. To summarize:

Add g0 and g1 parameters to the view factor functions in pvlib.bifacial.utils. These are analogous to x0 and x1 in vf_row_sky_2d_integ and extend the functions to subset the ground surface.
Change vf_ground_sky_2d_integ to use Hottel's crossed-string rule instead of burdensome numerical integration. This makes the npoints and vectorize parameters unnecessary.
Change some signatures in pvlib.bifacial.utils to be cleaner with the new calculations.
Minor edits in pvlib.bifacial.infinite_sheds to accommodate the utils changes
Create pvlib.bifacial.ant2d, which houses the model itself and uses the new utils functionality.

Let me know if it would help reviewers to split it up and review separate PRs, starting with utils.

echedey-ls

Some first impressions; also, you may want to link to it in other bifacial "See also" sections.

cwhanse

I'm OK reviewing the whole PR, if we can do it in a sequence of smaller review bites.

Co-Authored-By: Cliff Hansen <5393711+cwhanse@users.noreply.github.com>

cwhanse · 2026-05-20T15:22:36Z

    -------
    fgnd_sky : numeric
        Integration of view factor over the length between adjacent, interior
        rows.  Shape matches that of ``surface_tilt``. [unitless]


Replace surface_tilt or not, pending outcome of comment about tracker_rotation

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

williamhobbs · 2026-05-20T17:58:02Z

Is there a reason that pvlib.irradiance.perez_driesse is not an option? That would be useful to include if it's compatible.

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

kandersolar · 2026-05-20T20:35:13Z

Is there a reason that pvlib.irradiance.perez_driesse is not an option? That would be useful to include if it's compatible.

The only reason is that I did not think to include it in the reference paper, so including it here would be going beyond the reference. If no reviewers object to that in this case, I'd be fine adding it in (and maybe documenting it as an extension).

williamhobbs · 2026-05-20T20:38:20Z

I'd be fine adding it in (and maybe documenting it as an extension).

That sounds great to me!

…into ants2d

kandersolar added 30 commits September 29, 2025 14:15

ants2d and new VF code

d6d6f31

remove some cruft

99a7a81

add tests for ants2d._shaded_fraction

a6f22bb

refactoring and more tests

02686aa

tests for _apply_ground_slope

034efd9

tests for _apply_sky_diffuse_model

4748915

fix return shape and tests for vf_row_ground_2d_integ

d2bf3ad

fix return shape and tests for vf_row_sky_2d_integ

405649b

major docstring cleanup

7dd6853

standardize to "back" instead of "rear"

505d8d4

shape fixes, pandas out

8811daa

bugfix in unshaded ground fraction

0907682

add several tests for main function

8c792ec

test updates

9d28b75

better return type logic; more get_irradiance tests

2331023

expose max_rows, more get_irradiance tests

56fe82b

fix issue with horizontal array and large max_rows

920ec30

fix unshaded_ground_fraction for horizontal special case

403c0a4

fix row->ground VF edge case

24c8f32

switch default model from isotropic to perez

06f2a97

add hardcoded regression test

69105fd

alphabetize module imports

eaa8fd1

docstring work

98d1664

utils functions: make height and pitch optional

784877f

get infinite_sheds working again

2cbfb0d

polishing

7927422

fix output when surface angle is scalar but irrad is array

52d4fc2

simplify numpy import

39663ea

add option to return irradiance incident on ground surface

5a650e4

more tests for ground irradiance

28480f7

kandersolar added 8 commits April 30, 2026 09:46

deprecate npoints, vectorize

c8be126

fix deprecation version

69eaf67

lint

485eb0c

docstring cleanup

e4c0c51

whatsnew entries

30257a7

fix broken gallery example

a36841d

add reference docs entry and user guide description

611f9da

add test to cover untested branch

e81e250

kandersolar marked this pull request as ready for review April 30, 2026 15:36

echedey-ls reviewed May 4, 2026

View reviewed changes

Comment thread pvlib/bifacial/utils.py Outdated

Comment thread pvlib/bifacial/utils.py Outdated

cwhanse reviewed May 5, 2026

View reviewed changes

kandersolar and others added 2 commits May 6, 2026 14:24

feedback from review

5a4d792

Co-Authored-By: Cliff Hansen <5393711+cwhanse@users.noreply.github.com>

Merge branch 'main' into ants2d

f329c56

williamhobbs mentioned this pull request May 20, 2026

Create test branch for ANTS-2D bifacial irradiance model williamhobbs/pv-system-model#28

Open

cwhanse reviewed May 20, 2026

View reviewed changes

kandersolar and others added 2 commits May 20, 2026 11:59

Update pvlib/bifacial/utils.py

04583d8

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

adopt new description for phi

fa94412

Update pvlib/bifacial/utils.py

6dbcd22

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

kandersolar added 9 commits May 20, 2026 17:03

Merge branch 'main' into ants2d

0f185ed

changes from review

d3679fe

allow perez_driesse

ce481de

add reference to utils functions

043453a

move g0, g1 to end of function signatures

ac2424b

Merge remote-tracking branch 'upstream/main' into ants2d

4bca09d

fix whatsnew merge

fe8728f

Merge branch 'ants2d' of https://github.com/kandersolar/pvlib-python …

da62ab5

…into ants2d

update tests for pvlib#1867

1556356

Conversation

kandersolar commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

echedey-ls left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cwhanse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cwhanse May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

williamhobbs commented May 20, 2026

Uh oh!

kandersolar commented May 20, 2026

Uh oh!

williamhobbs commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kandersolar commented Apr 21, 2026 •

edited

Loading